Plugin Overview

HouseBot Winamp Device Overview

The HouseBot Winamp Plugin provides control of NullSofts Winamp media player application. The Plugin was designed to interact with Winamp version 2.x, but it can also be used to control version 5 and even version 3.x (see below).

The Winamp Device allows control of the Winamp application running on the HouseBot server through standard HouseBot Devices Properties. Functions that can be controlled by the Device include:

  • Playing status (Play, Pause, Stop)
  • Equalizer control. All frequencies and on/off
  • Playlist support using the PlayList Device
  • Playing MP3 or line-in stream*
  • Preamp level
  • Track time status and control
  • Visualization control

(*) Requires line-in Winamp plugin.

To get a free version of Winamp, visit http://www.winamp.com and download it.

Important: Before the WinAmp Device can be used, it is necessary to install the HouseBot Winamp proxy plugin. To install the HouseBot Winamp proxy plugin, copy the Gen_WinampProxy.dll file into the Winamp plugins directory. This file can be found in the HouseBot Plugins\Devices\Winamp_plugin directory. The proxy plugin does not have any configuration options. It is simply used as a way for the HouseBot Device plugin to communicate with Winamp.

Winamp 5.x

The Winamp 2.x plugin has been tested and is compatible with version 5.x. The name of the Plugin has not changed for backward compatibility reasons. The plugin manager specified in the Winamp 3.x setup is NOT needed.

Winamp 3.x

The Winamp 2.x plugin was designed to control Winamp version 2.x. It can, however, also be used to control Winamp 3.x by using the Winamp 2x Plugin Manager component for Winamp 3. The Plugin Manager can be downloaded from the Nullsoft web site at http://www.winamp.com/components3/detail.jhtml?componentId=118230.

The Winamp 3 application has a different executable name. For the Full path to file Property, make sure to use the studio.exe application name.

The Winamp 2x Plugin Manager does not support visualizations, so the visualization functionality of the HouseBot Plugin will NOT run the visualizations.


Configuring

Configuring the Winamp Device

Important: Before the WinAmp Device can be used, it is necessary to install the HouseBot Winamp proxy plugin. To install the HouseBot Winamp proxy plugin, copy the Gen_WinampProxy.dll file into the Winamp plugins directory. This file can be found in the HouseBot Plugins\Devices\Winamp_plugin directory. The proxy plugin does not have any configuration options. It is simply used as a way for the HouseBot Device plugin to communicate with Winamp.

To configure a Winamp Device:

  1. From the HouseBot main menu, select "File / New / Device...".
  2. The New Device Wizard will prompt you through the setup.
  3. Select the "No Hardware Interface Required" radio button.
  4. Select "WinAmp 2.x" as the type of Device.
  5. Give a unique and descriptive name to the Device.
  6. Enter the full path and file name to the WinAmp application (see below).

The Properties highlighted in RED are required.

Property | Description
A/V Status | This value controls the playing state of the track. Valid values are Stopped, Paused, Playing. To start a track playing, simply change this value to Playing. The Fast Forwarding, Fast Rewinding, and Recording values are not handled by the Winamp Device.
Bit Rate | This is a read-only Property that displays the encoded bit rate of the currently playing track.
Currently Active Play List | If using a Playlist, this value specifies either the HouseBot Playlist Device and Playlist name, or the name of the Winamp Device Playlist (e.g. "Play List 1") used. If using the Playlist Manager, the format of the Value is 'Device.Playlist_Property'. If not using a Playlist, this value should be left blank or set to None.
EQ Hz Level | There are 10 different Properties that control Winamp equalizer levels for various frequencies ranging from 60 Hz to 16 KHz. Valid values range from -20 to 20, where 0 is the default value.
Equalizer Enabled | This value controls the enabled state of the equalizer. Set this value to 1 to enable the equalizer. Set this value to 0 to disable the equalizer.
Full path to file | This value contains the full path and file name to the Winamp executable file. Do NOT enclose the path or file name with quotes.
Play File Name | This is a read-only Property that displays the name of the currently playing track. It does not include the path to the track or the extension.
Play List n | There are four user definable playlists that are managed by the Winamp Device. To use one of the Winamp playlists, the Currently Active Play List Property must be set to one of the four playlist names. The playlists are created and managed by using the Directory and List Theme controls from a Software Remote. For more information on Playlists, see the Playlist section.
Play List Song Number | When using a Playlist, this value indicates the current song number (index) that is playing. Valid values range from 0 to one less than the number of tracks/songs in the playlist. This property can be used to jump directly to a track in a playlist.
Play Source | This value contains the full path and file name to the track that is currently playing. If not using a playlist, this value can be used to play a specific track. When this value changes, the track will begin to play.
Preamp Level | This value controls the Winamp preamp level. Valid values are from -20 to 20, where 0 is the default value.
Sample Rate | This is a read-only Property that displays the sample rate of the MP3 track that is playing.
Song Length | This is a read-only Property that displays that length of the track that is playing.
Song Position | This value displays the amount of time that the currently playing track has been playing. To jump to a specific location in the track, this value can be changed to a value between 0 and the Song Length.
Visualization Name | This value is use to control Winamp visualizations. The value contains the file name to the visualization plugin without quotes. For example "C:\program files\winamp\plugins\vis_geis.dll". To disable the visualization, set the value to None. For more information on using visualizations, see the Visualizations section.
WinAmp Volume | This value is used to control the volume. Values range from 0 to 255.


Using the Device

The Winamp Device is typically controlled from a Software Remote. Tasks can be used in combination with Software Remotes to further control the Device.

If the Winamp application is not currently running, the Winamp Device will automatically start the application to play a track.

Individual tracks can be played by setting the Play Source to the full path and file name of the track to play. When the Play Source value is changed, the A/V Status will automatically change to Playing to play the track.

Managing the Winamp Device using individual track file names can be cumbersome. Using playlists provides the convience of having multiple lists of tracks. For more information on playlists, see the Playlists section.

Once configured, using the Winamp Device is very simple. To play a track, set the A/V Status Property value to Playing. To stop the track, set the Property to Stopped.

While playing, the song can be advanced by changing the Song Position Property to the desired location.

The equalizer frequencies can be changed at any time by changing the "EQ Hz Level" Properties. To represent the EQ settings on a Theme, use slider controls for each of the frequencies. Set the min/max of the sliders to -20 and 20.

Using the Line-In Plugin

In addition to playing standard MP3 tracks, the Winamp Device can be used as a simple pass through audio device. The Line-in plugin will simply take the audio stream of the default input device and stream it to the Winamp output. The advantage of using the pass-through feature is to leverage the Visualization functionality of Winamp and the control of the Software Remote.

To use the Line-In plugin, it must first be installed in Winamp. The Winamp Plugin can be downloaded from the Nullsoft web site at http://classic.winamp.com/plugins/detail.jhtml?componentId=84040. There is no configuration required. The Line-In plugin will use the default input device (this can be seen in the Line-In plugin configuration window).

In addition to the Line-in Winamp plugin, the HouseBot Winamp proxy plugin must also be installed. To install the HouseBot Winamp proxy plugin, copy the Gen_WinampProxy.dll file into the Winamp plugins directory. This file can be found in the HouseBot Plugins\Devices\Winamp_plugin directory.

To use the line-in plugin, simply set the Play Source Property Value to Line In. This will enable the Line-In Plugin.

Note:

  • There are several "Line-in" Plugins avaiable through the Nullsoft web site. The HouseBot Winamp Device works only with the line-in plugin (in_line.dll) developed by Jasper van de Gronde.


Playlists

A playlist is an ordered list of tracks. Playlists provide an easy way to organize your music by category or personal preference.

The WinAmp Device has support for two different types of playlists.

  1. Internal Playlists - These are playlists that are managed by the WinAmp Device itself.
  2. Playlist Manager - These are playlists that are managed by the Playlist Manager Device.

Common to both types of playlists is the ability to:

  • Switch playlists. To specify or change the currently playlist, change the Currently Active Play List Property Value to the new list.
  • Jump to tracks. To jump to a specific track in a playlist, change the Play List Song Number Property value to the index value of the track to play.

When the Playlist File Name is changed, the Playlist will automatically update the Play List Property and the Playlist Track Count Property with new values.

Internal Playlists

The WinAmp Device provides four playlists. These playlists can be managed by Software Remotes using the List, Directory, and List Button Theme controls. Using these controls, tracks in a playlist can be added, removed, and ordered.

To play an internal Playlist, set the Currently Active Play List Property Value to either "Play List 1", "Play List 2", "Play List 3", or "Play List 4", depending on which playlist to use.

Internal Playlists work well if you have a limited number of lists and often need to change the lists from a Software Remote. However, they can be limiting due to the need to manage them from the Software Remote. An alternative to the Internal Playlists are playlists managed by the Playlist Manager.

Playlist Manager

The Playlist Manger is a separate HouseBot Device that can manage any number of playlists using an external application. For information on configuring and using the Playlist Manager Device, see the on-line help for the Playlist Manager.

To use a playlist managed by the Playlist Manager Device, simply set the Currently Active Play List Property to point to the Playlist Manager Device and playlist Property. For example, if a Playlist Manager Device named PL Manager has been configured with a playlist that you wish to play, set the Currently Active Play List Property Value to "PL Manager.Play List".

Once the Currently Active Play List Property has been set to the PlayList manager Device, changing playlists is done by simply changing the playlist file name managed by the Playlist Manager Device.


Visualizations

The HouseBot Winamp Device supports Winamp visualizations. The visualization functionality allows HouseBot to enable a Winamp visualization plugin. The visualization will be displayed on the HouseBot server monitor only.

The Device can enable a visualization by changing the value of the Visualization Name Property. The value of this Property is set to the name of the Winamp visualization plugin DLL that is to be started. The plugin file name should also include the full path to the file. For example "C:\program files\Winamp\plugins\vis_geis.dll". To disable a visualization, set the Property Value to None.

Visualizations can be controlled by Software Remotes by using Property Change Buttons to set the Visualization Name Property of the Winamp Device to the desired visualization. If additional steps are required to fully setup the system for the visualizations, an Execute Task buttons can be used instead.

Notes:

  • The visualization will only be active if there is music playing.
  • If using Winamp 3.x, visualizations will not function.